HAL AES Functions

HAL AES Functions

STM32C562xx STM32C5A3xx STM32C542xx

group AES_Exported_Functions

Functions

hal_status_t HAL_AES_CBC_GetLastOutputIV ( const hal_aes_handle_t * haes , const uint8_t * p_last_iv , uint8_t last_iv_size )

Get the last output IV for CBC mode.

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_last_iv – Pointer to the user buffer to be updated with the last output IV

• last_iv_size – Size of the p_last_iv buffer

Return values :

• HAL_INVALID_PARAM – Invalid param return when the provided last output IV pointer is null or the handle pointer is null

• HAL_ERROR – Error return when the selected algorithm is not CBC algorithm or when the data_size_sum_byte is null

• HAL_OK – AES process is successfully accomplished

hal_status_t HAL_AES_CTR_GetLastOutputIV ( const hal_aes_handle_t * haes , const uint8_t * p_last_iv , uint8_t last_iv_size )

Get the last output IV for CTR mode.

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_last_iv – Pointer to the user buffer to be updated with the last output IV

• last_iv_size – Size of the p_last_iv buffer

Return values :

• HAL_INVALID_PARAM – Invalid param return when the provided last output IV pointer is null or the handle pointer is null

• HAL_ERROR – Error return when the selected algorithm is not CTR algorithm or when the data_size_sum_byte is null

• HAL_OK – AES process is successfully accomplished

Initialization and De-initialization functions

STM32C562xx STM32C5A3xx STM32C542xx

group AES_Exported_Functions_Group1

This subsection provides a set of functions allowing to initialize and de-initialize the AES/SAES peripheral:

• The HAL_AES_Init() API: Allows initializing the HAL AES driver so it can be configured and used to encrypt a plaintext or decrypt a ciphertext This API is the first API to call when using the HAL AES, it takes 2 parameters as input:

  • The HAL AES handle: A pointer to a hal_aes_handle_t structure

  • The AES instance: A value from the enumeration hal_aes_t

• The HAL_AES_DeInit() API: Allows de-initializing the HAL AES driver by:

  • Disabling the AES/SAES peripheral

  • Abort DMA input and output transfers

  • De-initializing the current handle object

  • Resetting the handle global state to the HAL_AES_STATE_RESET

Functions

hal_status_t HAL_AES_Init ( hal_aes_handle_t * haes , hal_aes_t instance )

Initialize the HAL AES handle and associate it to an instance.

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• instance – hal_aes_t enumerated type variable to be set according to the physical instance

Return values :

• HAL_INVALID_PARAM – Invalid param return when the AES handle is NULL

• HAL_OK – The HAL AES driver is initialized according to the given handle and instance

void HAL_AES_DeInit ( hal_aes_handle_t * haes )

De-initialize the AES/SAES peripheral.

Parameters :

haes – Pointer to a hal_aes_handle_t structure

Configuration functions

STM32C562xx STM32C5A3xx STM32C542xx

group AES_Exported_Functions_Group2

This subsection provides a set of functions allowing to configure the AES/SAES peripheral through three steps:

• Step1: Chaining mode(algorithm) configuration APIs:

  • HAL_AES_ECB_SetConfig():Allowing to configure the AES/SAES peripheral with the ECB algorithm

  • HAL_AES_CBC_SetConfig():Allowing to configure the AES/SAES peripheral with the CBC algorithm

  • HAL_AES_CTR_SetConfig():Allowing to configure the AES peripheral with the CTR algorithm

  • HAL_AES_GCM_GMAC_SetConfig():Allowing to configure the AES peripheral with the GCM_GMAC algorithms

  • HAL_AES_CCM_SetConfig():Allowing to configure the AES peripheral with the CCM algorithm

• Step2: Key configuration APIs:

  • HAL_AES_SetNormalKey():Allowing to configure the application normal key

  • HAL_AES_SetHWKey():Allowing to configure the SAES peripheral hardware key for normal, wrap or share mode use

  • HAL_AES_SetSharedKey():Allowing to configure the AES peripheral shared key

• Step3: Data swapping mode configuration APIs:

  • HAL_AES_SetDataSwapping():Allowing to configure the data swapping mode

  • HAL_AES_GetDataSwapping():Allowing to retrieve the data swapping mode

• Other configuration APIs:

  • HAL_AES_EnableKeyProtection():Allowing to protect the SAES key from being accessed by another peripheral

  • HAL_AES_DisableKeyProtection():Allowing to disable the SAES key protection

  • HAL_AES_IsEnabledKeyProtection():Allowing to check if the SAES key protection is enabled or disabled

Functions

hal_status_t HAL_AES_ECB_SetConfig ( hal_aes_handle_t * haes )

Configure the AES/SAES peripheral with ECB algorithm.

Note

The user has not to set any parameter

Parameters :

haes – Pointer to a hal_aes_handle_t structure

Return values :

• HAL_INVALID_PARAM – Invalid param return when the AES handle is NULL

• HAL_ERROR – Error detected while fetching a random number from RNG peripheral (only for SAES instance)

• HAL_OK – AES/SAES peripheral has been correctly configured with ECB algorithm

hal_status_t HAL_AES_CBC_SetConfig ( hal_aes_handle_t * haes , const uint32_t * p_init_vect )

Configure the AES/SAES peripheral with CBC algorithm.

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_init_vect – Pointer to const uint32_t four words buffer provided by the user. For CBC algorithm, the init vector is used to process only the first data block

Return values :

• HAL_INVALID_PARAM – Invalid param return when the provided init vector pointer or handle pointer is null

• HAL_ERROR – Error detected while fetching a random number from RNG peripheral (only for SAES instance)

• HAL_OK – AES/SAES peripheral has been correctly configured with CBC algorithm

hal_status_t HAL_AES_CTR_SetConfig ( hal_aes_handle_t * haes , const uint32_t * p_init_vect )

Configure the AES/SAES peripheral with the CTR algorithm.

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_init_vect – Pointer to const uint32_t four words buffer provided by the user. For CTR algorithm, the init vector is used to process each data block

Return values :

• HAL_INVALID_PARAM – Invalid param return when the provided init vector pointer is null or the handle pointer is null

• HAL_ERROR – Error detected while fetching a random number from RNG peripheral (only for SAES instance)

• HAL_OK – AES/SAES peripheral has been correctly configured with the CTR algorithm

hal_status_t HAL_AES_GCM_GMAC_SetConfig ( hal_aes_handle_t * haes , const hal_aes_gcm_config_t * p_config )

Configure the AES/SAES peripheral with the GCM_GMAC algorithm.

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_config – Pointer to a hal_aes_gcm_config_t structure that contains the AES configuration with GCM_GMAC algorithms

Return values :

• HAL_INVALID_PARAM – Invalid param return when:

  • The configuration structure pointer is null

  • The provided init vector pointer within the configuration structure is null

  • The provided header within the configuration structure is null but its size is not null

  • The handle pointer is null

• HAL_ERROR – Error detected while fetching a random number from RNG peripheral (only for SAES instance)

• HAL_OK – AES/SAES peripheral has been correctly configured with the GCM_GMAC algorithm

hal_status_t HAL_AES_CCM_SetConfig ( hal_aes_handle_t * haes , const hal_aes_ccm_config_t * p_config )

Configure the AES/SAES peripheral with the CCM algorithm.

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_config – Pointer to a hal_aes_ccm_config_t structure

Return values :

• HAL_INVALID_PARAM – Invalid param return when:

  • The configuration structure pointer is null

  • The provided b0 within the configuration structure is null

  • The provided header within the configuration structure is null but its size is not null

  • The handle pointer is null

• HAL_ERROR – Error detected while fetching a random number from RNG peripheral (only for SAES instance)

• HAL_OK – AES/SAES peripheral has been correctly configured with the CCM algorithm

hal_status_t HAL_AES_SetNormalKey ( hal_aes_handle_t * haes , hal_aes_key_size_t key_size , const uint32_t * p_key )

Configure the AES Normal key(key size, key value), supports both AES and SAES instances.

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• key_size – AES key size with a hal_aes_key_size_t type

• p_key – A uint32_t AES key that must be coherent with the key_size

Return values :

• HAL_INVALID_PARAM – Invalid param return when the provided pointer key is null or the handle pointer is null

• HAL_ERROR – Error when loading the key into registers exceeds the dedicated timeout

• HAL_OK – Normal key has been configured

hal_status_t HAL_AES_SetDataSwapping ( hal_aes_handle_t * haes , hal_aes_data_swapping_t data_swapping )

Configure the AES data swapping.

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• data_swapping – AES data swapping with a hal_aes_data_swapping_t type

Return values :

HAL_OK – The AES data swapping mode is set

hal_aes_data_swapping_t HAL_AES_GetDataSwapping ( const hal_aes_handle_t * haes )

Retrieve the AES configured data swapping.

Parameters :

haes – Pointer to a hal_aes_handle_t structure

Return values :

• HAL_AES_NO_SWAP – The bit order of the input and output data is not affected

• HAL_AES_HALFWORD_SWAP – The bit-reversal is done by halfword Ex: 0011 1100 0100 1101 –> 0100 1101 0011 1100

• HAL_AES_BYTE_SWAP – The bit-reversal is done by byte Ex: 0011 1100 0100 1101 –> 1101 0100 1100 0011

• HAL_AES_BIT_SWAP – The bit-reversal is done by bit Ex: 0011 1100 0100 1101 –> 1011 0010 0011 1100

Process functions

STM32C562xx STM32C5A3xx STM32C542xx

group AES_Exported_Functions_Group3

This subsection provides a set of functions allowing to perform AES processing and manage suspension/resumption:

• HAL_AES_Encrypt():Allowing to encrypt a plaintext within a dedicated timeout

• HAL_AES_Decrypt():Allowing to decrypt a ciphertext within a dedicated timeout

• HAL_AES_Encrypt_IT():Allowing to encrypt a plaintext using the AES interrupt

• HAL_AES_Decrypt_IT():Allowing to decrypt a ciphertext using the AES interrupt

• HAL_AES_Encrypt_DMA():Allowing to encrypt a plaintext using the DMA

• HAL_AES_Decrypt_DMA():Allowing to decrypt a ciphertext using the DMA

• HAL_AES_RequestSuspend():Allowing to request an IT process suspension

• HAL_AES_SaveContext():Allowing to save the context of the suspended process to start another high priority one

• HAL_AES_RestoreContext():Allowing to restore the saved context of the low prior process

• HAL_AES_Resume():Allowing to resume the low prior process

Functions

hal_status_t HAL_AES_Encrypt ( hal_aes_handle_t * haes , const void * p_input , uint16_t size_byte , void * p_output , uint32_t timeout_ms )

Encrypt user data in polling mode.

• For ECB, CBC or CTR algorithms:

  • The padding is not supported.

  • Only the encryption of the plaintext is available (no preparation for tag generation).

• For GCM algorithm:- HAL_AES_Encrypt() is used either to:

  • Encrypt a plaintext and use the header to prepare for the tag generation.

  • Or just do the encryption (header null).

  • Or just prepare for tag generation (plaintext null).

• For GMAC algorithm: Prepare for the tag generation only (plaintext null).

• For CCM algorithm:- HAL_AES_Encrypt() is used either to:

  • Encrypt a plaintext and use the header to prepare for the tag generation.

  • Or just do the encryption (header null).

  • Or just prepare for tag generation (plaintext null)(not recommended by NIST).

Warning

No swapped user data must be provided in big-endian. When data are provided in little-endian, the user must configure the swapping mode before starting the process (ex when data are provided as little-endian bytes, the swap mode must be set to HAL_AES_BYTE_SWAP or when data are provided as little-endian halfwords, the swap mode must be set to HAL_AES_HALFWORD_SWAP)

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_input – Pointer to aligned const void plaintext

• size_byte – Length of the plaintext buffer that must be in byte

• p_output – Pointer to aligned void data buffer to be filled with the encrypted text

• timeout_ms – Specify timeout value in milliseconds

Return values :

• HAL_INVALID_PARAM – For ECB, CBC or CTR algorithms Invalid param return when:

  • The provided input data buffer pointer is null

  • Or the output data buffer pointer is null

  • Or the input buffer is empty For GCM_GMAC or CCM algorithms Invalid param return when:

  • The provided input data buffer pointer is null but its size is # 0U The handle pointer is null The provided timeout is null

• HAL_BUSY – Another AES process is ongoing

• HAL_ERROR – Error return when the loaded key is invalid

• HAL_TIMEOUT – AES encryption exceeds user timeout

• HAL_OK – AES encryption is successfully accomplished

hal_status_t HAL_AES_Decrypt ( hal_aes_handle_t * haes , const void * p_input , uint16_t size_byte , void * p_output , uint32_t timeout_ms )

Decrypt user data in polling mode.

• For ECB, CBC or CTR algorithms:

  • The padding is not supported.

  • Only the decryption of the ciphertext is available (no preparation for tag generation).

• For GCM algorithm:- HAL_AES_Decrypt() is used either to:

  • Decrypt a ciphertext and use the header to prepare for the tag generation.

  • Or just do the decryption (header null).

  • Or just prepare for tag generation (ciphertext null).

• For GMAC algorithm: Prepare for the tag generation only (ciphertext null).

• For CCM algorithm:- HAL_AES_Decrypt() is used either to:

  • Decrypt a ciphertext and use the header to prepare for the tag generation.

  • Or just do the decryption (header null).

  • Or just prepare for tag generation (ciphertext null)(not recommended by NIST).

Warning

No swapped user data must be provided in big-endian. When data are provided in little-endian, the user must configure the swapping mode before starting the process (ex when data are provided as little-endian bytes, the swap mode must be set to HAL_AES_BYTE_SWAP or when data are provided as little-endian halfwords, the swap mode must be set to HAL_AES_HALFWORD_SWAP)

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_input – Pointer to aligned const void ciphertext

• size_byte – Length of the ciphertext buffer that must be in byte

• p_output – Pointer to aligned void data buffer to be filled with the decrypted text

• timeout_ms – Specify timeout value in milliseconds

Return values :

• HAL_INVALID_PARAM – For ECB, CBC or CTR algorithms Invalid param return when:

  • The provided input data buffer pointer is null

  • Or the output data buffer pointer is null

  • Or the input buffer is empty For GCM_GMAC or CCM algorithms Invalid param return when:

  • The provided input data buffer pointer is null but its size is # 0U The handle pointer is null The provided timeout is null

• HAL_BUSY – Another AES process is ongoing

• HAL_ERROR – Error return when the loaded key is invalid or when the key derivation exceeds the dedicated timeout

• HAL_TIMEOUT – AES decryption exceeds user timeout

• HAL_OK – AES decryption is successfully accomplished

hal_status_t HAL_AES_Encrypt_IT ( hal_aes_handle_t * haes , const void * p_input , uint16_t size_byte , void * p_output )

Encrypt user data in interrupt mode.

• For ECB, CBC or CTR algorithms:

  • The padding is not supported.

  • Only the encryption of the plaintext is available (no preparation for tag generation).

• For GCM algorithm:- HAL_AES_Encrypt_IT() is used either to:

  • Encrypt a plaintext and use the header to prepare for the tag generation.

  • Or just do the encryption (header null).

  • Or just prepare for tag generation (plaintext null).

• For GMAC algorithm: Prepare for the tag generation only (plaintext null).

• For CCM algorithm:- HAL_AES_Encrypt_IT() is used either to:

  • Encrypt a plaintext and use the header to prepare for the tag generation.

  • Or just do the encryption (header null).

  • Or just prepare for tag generation (plaintext null)(not recommended by NIST).

Warning

No swapped user data must be provided in big-endian. When data are provided in little-endian, the user must configure the swapping mode before starting the process (ex when data are provided as little-endian bytes, the swap mode must be set to HAL_AES_BYTE_SWAP or when data are provided as little-endian halfwords, the swap mode must be set to HAL_AES_HALFWORD_SWAP)

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_input – Pointer to aligned const void plaintext

• size_byte – Length of the plaintext buffer that must be in byte

• p_output – Pointer to aligned void data buffer to be filled with the encrypted text

Return values :

• HAL_INVALID_PARAM – For ECB, CBC or CTR algorithms Invalid param return when:

  • The provided input data buffer pointer is null

  • Or the output data buffer pointer is null

  • Or the input buffer is empty For GCM_GMAC or CCM algorithms Invalid param return when:

  • The provided input data buffer pointer is null but its size is # 0U The handle pointer is null

• HAL_BUSY – Another AES process is ongoing

• HAL_ERROR – Error return when the loaded key is invalid

• HAL_OK – AES encryption is successfully accomplished

hal_status_t HAL_AES_Decrypt_IT ( hal_aes_handle_t * haes , const void * p_input , uint16_t size_byte , void * p_output )

Decrypt user data in interrupt mode.

• For ECB, CBC or CTR algorithms:

  • The padding is not supported.

  • Only the decryption of the ciphertext is available (no preparation for tag generation).

• For GCM algorithm:- HAL_AES_Decrypt_IT() is used either to:

  • Decrypt a ciphertext and use the header to prepare for the tag generation.

  • Or just do the decryption (header null).

  • Or just prepare for tag generation (ciphertext null).

• For GMAC algorithm: Prepare for the tag generation only (ciphertext null).

• For CCM algorithm:- HAL_AES_Decrypt_IT() is used either to:

  • Decrypt a ciphertext and use the header to prepare for the tag generation.

  • Or just do the decryption (header null).

  • Or just prepare for tag generation (ciphertext null)( not recommended by NIST).

Warning

No swapped user data must be provided in big-endian. When data are provided in little-endian, the user must configure the swapping mode before starting the process (ex when data are provided as little-endian bytes, the swap mode must be set to HAL_AES_BYTE_SWAP or when data are provided as little-endian halfwords, the swap mode must be set to HAL_AES_HALFWORD_SWAP)

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_input – Pointer to aligned const void ciphertext

• size_byte – Length of the ciphertext buffer that must be in byte

• p_output – Pointer to aligned void data buffer to be filled with the decrypted text

Return values :

• HAL_INVALID_PARAM – For ECB, CBC or CTR algorithms Invalid param return when:

  • The provided input data buffer pointer is null

  • Or the output data buffer pointer is null

  • Or the input buffer is empty For GCM_GMAC or CCM algorithms Invalid param return when:

  • The provided input data buffer pointer is null but its size is # 0U The handle pointer is null

• HAL_BUSY – Another AES process is ongoing

• HAL_ERROR – Error return when the loaded key is invalid or when the key derivation exceeds the dedicated timeout

• HAL_OK – AES decryption is successfully accomplished

hal_status_t HAL_AES_Encrypt_DMA ( hal_aes_handle_t * haes , const void * p_input , uint16_t size_byte , void * p_output )

Encrypt user data in DMA mode.

• For ECB, CBC or CTR algorithms:

  • The padding is not supported.

  • Only the encryption of the plaintext is available (no preparation for tag generation).

• For GCM algorithm:- HAL_AES_Encrypt_DMA() is used either to:

  • Encrypt a plaintext and use the header to prepare for the tag generation.

  • Or just do the encryption (header null).

  • Or just prepare for tag generation (plaintext null).

• For GMAC algorithm: Prepare for the tag generation only (plaintext null).

• For CCM algorithm:- HAL_AES_Encrypt_DMA() is used either to:

  • Encrypt a plaintext and use the header to prepare for the tag generation.

  • Or just do the encryption (header null).

  • Or just prepare for tag generation (plaintext null)(not recommended by NIST).

Warning

No swapped user data must be provided in big-endian. When data are provided in little-endian, the user must configure the swapping mode before starting the process (ex when data are provided as little-endian bytes, the swap mode must be set to HAL_AES_BYTE_SWAP or when data are provided as little-endian halfwords, the swap mode must be set to HAL_AES_HALFWORD_SWAP)

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_input – Pointer to aligned const void plaintext

• size_byte – Length of the plaintext buffer that must be in byte

• p_output – Pointer to aligned void data buffer to be filled with the encrypted text

Return values :

• HAL_INVALID_PARAM – For ECB, CBC or CTR algorithms Invalid param return when:

  • The provided input data buffer pointer is null

  • Or the output data buffer pointer is null

  • Or the input buffer is empty For GCM_GMAC or CCM algorithms Invalid param return when:

  • The provided input data buffer pointer is null but its size is # 0U The handle pointer is null

• HAL_BUSY – Another AES process is ongoing

• HAL_ERROR – Error return when the loaded key is invalid

• HAL_OK – AES encryption is successfully accomplished

hal_status_t HAL_AES_Decrypt_DMA ( hal_aes_handle_t * haes , const void * p_input , uint16_t size_byte , void * p_output )

Decrypt user data in DMA mode.

• For ECB, CBC or CTR algorithms:

  • The padding is not supported.

  • Only the decryption of the ciphertext is available (no preparation for tag generation).

• For GCM algorithm:- HAL_AES_Decrypt_DMA() is used either to:

  • Decrypt a ciphertext and use the header to prepare for the tag generation.

  • Or just do the decryption (header null).

  • Or just prepare for tag generation (ciphertext null).

• For GMAC algorithm: Prepare for the tag generation only (ciphertext null).

• For CCM algorithm:- HAL_AES_Decrypt_DMA() is used either to:

  • Decrypt a ciphertext and use the header to prepare for the tag generation.

  • Or just do the decryption (header null).

  • Or just prepare for tag generation (ciphertext null)(not recommended by NIST).

Warning

No swapped user data must be provided in big-endian. When data are provided in little-endian, the user must configure the swapping mode before starting the process (ex when data are provided as little-endian bytes, the swap mode must be set to HAL_AES_BYTE_SWAP or when data are provided as little-endian halfwords, the swap mode must be set to HAL_AES_HALFWORD_SWAP)

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_input – Pointer to aligned const void ciphertext

• size_byte – Length of the ciphertext buffer that must be in byte

• p_output – Pointer to aligned void data buffer to be filled with the decrypted text

Return values :

• HAL_INVALID_PARAM – For ECB, CBC or CTR algorithms Invalid param return when:

  • The provided input data buffer pointer is null

  • Or the output data buffer pointer is null

  • Or the input buffer is empty For GCM_GMAC or CCM algorithms Invalid param return when:

  • The provided input data buffer pointer is null but its size is # 0U The handle pointer is null

• HAL_BUSY – Another AES process is ongoing

• HAL_ERROR – Error return when the loaded key is invalid or when the key derivation exceeds the dedicated timeout

• HAL_OK – AES decryption is successfully accomplished

hal_status_t HAL_AES_RequestSuspend ( hal_aes_handle_t * haes )

Request suspension for AES interrupt mode processing.

Note

Set the handle field suspend_request to HAL_AES_SUSPEND so that the on-going AES processing is suspended as soon as the required conditions are met (The current block is entirely processed and it’s not the last one)

Parameters :

haes – Pointer to a hal_aes_handle_t structure

Return values :

• HAL_INVALID_PARAM – When the handle pointer is NULL.

• HAL_OK – The AES processing suspension is well requested

hal_status_t HAL_AES_Resume ( hal_aes_handle_t * haes )

Resumption of the suspended AES processing.

Note

Processing restarts at the exact point where it was suspended, if the AES context has been changed HAL_AES_SaveContext and HAL_AES_RestoreContext must be used before resumption.

Parameters :

haes – Pointer to a hal_aes_handle_t structure

Return values :

• HAL_INVALID_PARAM – When the handle pointer is NULL.

• HAL_BUSY – Another AES process is ongoing

• HAL_OK – AES suspended processing is resumed

hal_status_t HAL_AES_SaveContext ( hal_aes_handle_t * haes , hal_aes_save_context_t * p_context )

Save parameters of the suspended AES processing.

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_context – Pointer to a hal_aes_save_context_t structure where to store the parameters of the suspend AES processing

Return values :

• HAL_INVALID_PARAM – The provided save context pointer structure or the handle pointer is null

• HAL_OK – AES suspended processing parameters are saved

hal_status_t HAL_AES_RestoreContext ( hal_aes_handle_t * haes , const hal_aes_save_context_t * p_context )

Resumption for the saved parameters of the suspended AES processing.

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_context – Pointer to a hal_aes_save_context_t structure where the parameters of the suspend AES processing are stored

Return values :

• HAL_INVALID_PARAM – When the handle pointer is NULL.

• HAL_ERROR – AES key derivation exceeds the dedicated timeout

• HAL_OK – AES suspended processing parameters are restored

IRQHandler,Callbacks and, Link DMA functions

STM32C562xx STM32C5A3xx STM32C542xx

group AES_Exported_Functions_Group4

This subsection provides the IRQHandler and a set of callback functions allowing to manage the data transfer between the user input/output buffer and the AES/SAES peripheral:

• HAL_AES_IRQHandler():Allowing to handle the AES interrupts

• HAL_AES_InCpltCallback():Input transfer complete callback

• HAL_AES_OutCpltCallback():Output transfer complete callback

• HAL_AES_ErrorCallback():Error callback

• HAL_AES_SuspendCallback():Suspend callback

• HAL_AES_RegisterInTransferCpltCallback():Allowing to register the input transfer complete callback

• HAL_AES_RegisterOutTransferCpltCallback():Allowing to register the output transfer complete callback

• HAL_AES_RegisterErrorCallback():Allowing to register the error callback

• HAL_AES_RegisterSuspendCallback():Allowing to register the suspend callback

• HAL_AES_SetInDMA():Allowing to link the input FIFO HAL DMA handle into the HAL AES handle

• HAL_AES_SetOutDMA():Allowing to link the output FIFO HAL DMA handle into the HAL AES handle

Functions

void HAL_AES_IRQHandler ( hal_aes_handle_t * haes )

Handle any AES interrupt.

Parameters :

haes – Pointer to a hal_aes_handle_t structure

void HAL_AES_InCpltCallback ( hal_aes_handle_t * haes )

Input FIFO transfer completed callback.

Parameters :

haes – Pointer to a hal_aes_handle_t structure

void HAL_AES_OutCpltCallback ( hal_aes_handle_t * haes )

Output FIFO transfer completed callback.

Parameters :

haes – Pointer to a hal_aes_handle_t structure

void HAL_AES_ErrorCallback ( hal_aes_handle_t * haes )

Error callback.

Parameters :

haes – Pointer to a hal_aes_handle_t structure

void HAL_AES_SuspendCallback ( hal_aes_handle_t * haes )

Suspend callback.

Parameters :

haes – Pointer to a hal_aes_handle_t structure

hal_status_t HAL_AES_RegisterInTransferCpltCallback ( hal_aes_handle_t * haes , hal_aes_cb_t p_callback )

Register the input transfer complete callback.

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_callback – Pointer to the hal_aes_cb_t callback function.

Return values :

• HAL_INVALID_PARAM – When the callback pointer is NULL.

• HAL_OK – Callback registered successfully.

hal_status_t HAL_AES_RegisterOutTransferCpltCallback ( hal_aes_handle_t * haes , hal_aes_cb_t p_callback )

Register the output transfer complete callback.

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_callback – Pointer to the hal_aes_cb_t callback function.

Return values :

• HAL_INVALID_PARAM – When the callback pointer is NULL.

• HAL_OK – Callback registered successfully.

hal_status_t HAL_AES_RegisterErrorCallback ( hal_aes_handle_t * haes , hal_aes_cb_t p_callback )

Register the error callback.

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_callback – Pointer to the hal_aes_cb_t callback function.

Return values :

• HAL_INVALID_PARAM – When the callback pointer is NULL.

• HAL_OK – Callback registered successfully.

hal_status_t HAL_AES_RegisterSuspendCallback ( hal_aes_handle_t * haes , hal_aes_cb_t p_callback )

Register the suspend callback.

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_callback – Pointer to the hal_aes_cb_t callback function.

Return values :

• HAL_INVALID_PARAM – When the callback pointer is NULL.

• HAL_OK – Callback registered successfully.

hal_status_t HAL_AES_SetInDMA ( hal_aes_handle_t * haes , hal_dma_handle_t * hdma_in )

Link/Store Input FIFO HAL DMA handle into the HAL AES handle.

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• hdma_in – Pointer to a hal_dma_handle_t

Return values :

• HAL_INVALID_PARAM – When the DMA handle pointer is NULL

• HAL_OK – The DMA handle has been correctly linked to the AES handle

hal_status_t HAL_AES_SetOutDMA ( hal_aes_handle_t * haes , hal_dma_handle_t * hdma_out )

Link/Store Output FIFO HAL DMA handle into the HAL AES handle.

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• hdma_out – Pointer to a hal_dma_handle_t

Return values :

• HAL_INVALID_PARAM – When the DMA handle pointer is NULL

• HAL_OK – The DMA handle has been correctly linked to the AES handle

Peripheral State, Error and Get last IV functions

STM32C562xx STM32C5A3xx STM32C542xx

group AES_Exported_Functions_Group5

This subsection provides a set of functions allowing to get the AES error information and state:

• HAL_AES_GetState():Allowing to retrieve the AES state

• HAL_AES_GetLastErrorCodes():Allowing to retrieve the AES error code

• HAL_AES_SetUserData():Allowing to store application user data pointer into the handle

• HAL_AES_GetUserData():Allowing to retrieve the application user data pointer from the handle

• HAL_AES_CBC_GetLastOutputIV():Allowing to retrieve the the last output IV for CBC mode.

• HAL_AES_CTR_GetLastOutputIV():Allowing to retrieve the the last output IV for CTR mode.

Functions

hal_aes_state_t HAL_AES_GetState ( const hal_aes_handle_t * haes )

Retrieve the HAL AES Global State.

Parameters :

haes – Pointer to a hal_aes_handle_t structure

Return values :

• HAL_AES_STATE_RESET – AES/SAES peripheral is not yet initialized

• HAL_AES_STATE_INIT – AES/SAES peripheral is initialized but not yet configured

• HAL_AES_STATE_IDLE – AES/SAES peripheral is initialized and configured

• HAL_AES_STATE_ACTIVE – AES internal processing is ongoing

• HAL_AES_STATE_SUSPENDED – AES internal processing is suspended

uint32_t HAL_AES_GetLastErrorCodes ( const hal_aes_handle_t * haes )

Get last error codes.

Parameters :

haes – Pointer to a hal_aes_handle_t structure

Return values :

uint32_t – Last error codes which can be a combination of Error Code definition reflecting the process asynchronous errors

void HAL_AES_SetUserData ( hal_aes_handle_t * haes , const void * p_user_data )

Store application user data pointer into the handle.

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_user_data – Pointer to the user data

const void * HAL_AES_GetUserData ( const hal_aes_handle_t * haes )

Retrieve the application user data pointer from the handle.

Parameters :

haes – Pointer to a hal_aes_handle_t structure

Return values :

Pointer – to the user data

hal_status_t HAL_AES_CBC_GetLastOutputIV ( const hal_aes_handle_t * haes , const uint8_t * p_last_iv , uint8_t last_iv_size )

Get the last output IV for CBC mode.

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_last_iv – Pointer to the user buffer to be updated with the last output IV

• last_iv_size – Size of the p_last_iv buffer

Return values :

• HAL_INVALID_PARAM – Invalid param return when the provided last output IV pointer is null or the handle pointer is null

• HAL_ERROR – Error return when the selected algorithm is not CBC algorithm or when the data_size_sum_byte is null

• HAL_OK – AES process is successfully accomplished

hal_status_t HAL_AES_CTR_GetLastOutputIV ( const hal_aes_handle_t * haes , const uint8_t * p_last_iv , uint8_t last_iv_size )

Get the last output IV for CTR mode.

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_last_iv – Pointer to the user buffer to be updated with the last output IV

• last_iv_size – Size of the p_last_iv buffer

Return values :

• HAL_INVALID_PARAM – Invalid param return when the provided last output IV pointer is null or the handle pointer is null

• HAL_ERROR – Error return when the selected algorithm is not CTR algorithm or when the data_size_sum_byte is null

• HAL_OK – AES process is successfully accomplished

Tag Generating functions

STM32C562xx STM32C5A3xx STM32C542xx

group AES_Exported_Functions_Group6

This subsection provides a set of functions allowing TAG generation for GCM and CCM algorithms:

• HAL_AES_GCM_GenerateAuthTAG():Allowing to generate a tag for GCM algorithm

• HAL_AES_CCM_GenerateAuthTAG():Allowing to generate a tag for CCM algorithm

Functions

hal_status_t HAL_AES_GCM_GenerateAuthTAG ( hal_aes_handle_t * haes , uint32_t * p_auth_tag , uint32_t timeout_ms )

Generate the GCM authentication TAG, available only with AES instance. This API can only be called after accomplishing either an encryption or a decryption process.

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_auth_tag – Pointer to the authentication buffer the p_auth_tag generated here is 128bits length, if the TAG length is less than 128bits, user must consider only the valid part of p_auth_tag buffer which corresponds exactly to TAG length.

• timeout_ms – Specify Timeout value in milliseconds

Return values :

• HAL_INVALID_PARAM – The provided input tag pointer is null

• HAL_BUSY – Another AES process is ongoing

• HAL_TIMEOUT – AES tag generation exceeds user timeout

• HAL_ERROR – AES tag generation sequence is not well performed

• HAL_OK – AES tag is successfully generated

hal_status_t HAL_AES_CCM_GenerateAuthTAG ( hal_aes_handle_t * haes , uint32_t * p_auth_tag , uint32_t timeout_ms )

Generate the CCM authentication TAG, available only with AES instance. This API can only be called after accomplishing either an encryption or a decryption process.

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_auth_tag – Pointer to the authentication buffer the p_auth_tag generated here is 128bits length, if the TAG length is less than 128bits, user must consider only the valid part of p_auth_tag buffer which corresponds exactly to TAG length.

• timeout_ms – Specify Timeout value in milliseconds

Return values :

• HAL_INVALID_PARAM – The provided input tag pointer is null

• HAL_BUSY – Another AES process is ongoing

• HAL_TIMEOUT – AES tag generation exceeds user timeout

• HAL_ERROR – AES tag generation sequence is not well performed

• HAL_OK – AES tag is successfully generated

Static Inlines functions

STM32C562xx STM32C5A3xx STM32C542xx

group AES_Exported_Functions_Group8

This section provides functions allowing to manage AES interrupts and flags:

• HAL_AES_GetFlag():Allowing to return the state of a flag

• HAL_AES_ClearFlagRDWRERR():Allowing to clear the read/write error flag

• HAL_AES_ClearFlagCC():Allowing to clear the computation complete flag

• HAL_AES_ClearFlagKERR():Allowing to clear the invalid key error flag #if defined(SAES)

• HAL_AES_ClearFlagRNGERR():Allowing to clear the AES RNG error flag #endif

• HAL_AES_GetITSource():Allowing to return the state of an interrupt

• HAL_AES_EnableIT():Allowing to enable an AES interrupt

• HAL_AES_DisableIT():Allowing to disable an AES interrupt

Functions

uint32_t HAL_AES_GetFlag ( const hal_aes_handle_t * haes , uint32_t flag )

Check whether the specified AES status flag is set or not.

Parameters :

• haes – Specifies the AES handle

• flag – Specifies the flag to check, this parameter can be one of the following values:

  • HAL_AES_FLAG_KEYVALID Key valid flag

  • HAL_AES_FLAG_BUSY GCM process suspension forbidden or transferring a shared key from SAES IP.

  • HAL_AES_FLAG_WRERR Write Error flag

  • HAL_AES_FLAG_RDERR Read Error flag

  • HAL_AES_FLAG_CC Computation Complete flag

  • HAL_AES_FLAG_KERR Key error flag

  • HAL_AES_FLAG_RDWRERR Read/write Error flag #if defined(SAES)

  • HAL_AES_FLAG_RNGERR RNG Error flag #endif

    @retval uint32_t The state of flag (0 or 1).
    

void HAL_AES_ClearFlagRDWRERR ( hal_aes_handle_t * haes )

Clear the AES Read/write error flag.

Parameters :

haes – Specifies the AES handle

void HAL_AES_ClearFlagCC ( hal_aes_handle_t * haes )

Clear the AES computation complete flag.

Parameters :

haes – Specifies the AES handle

void HAL_AES_ClearFlagKERR ( hal_aes_handle_t * haes )

Clear the AES invalid key error flag.

Parameters :

haes – Specifies the AES handle

uint32_t HAL_AES_GetITSource ( const hal_aes_handle_t * haes , uint32_t interrupt )

Check whether the specified AES interrupt source is enabled or not.

Parameters :

• haes – Specifies the AES handle

• interrupt – AES interrupt source to check This parameter can be one of the following values:

  • HAL_AES_IT_RDWRERR Error interrupt (used for RDERR and WRERR)

  • HAL_AES_IT_CC Computation Complete interrupt

  • HAL_AES_IT_KERR Key error interrupt

  • HAL_AES_IT_RNGERR RNG error interrupt

Return values :

uint32_t – State of interruption (0 or 1).

void HAL_AES_EnableIT ( hal_aes_handle_t * haes , uint32_t interrupt )

Enable the AES interrupt.

Parameters :

• haes – Specifies the AES handle

• interrupt – AES Interrupt This parameter can be a combination of the following values:

  • HAL_AES_IT_RDWRERR Error interrupt (used for RDERR and WRERR)

  • HAL_AES_IT_CC Computation Complete interrupt

  • HAL_AES_IT_KERR Key error interrupt

  • HAL_AES_IT_RNGERR RNG error interrupt

void HAL_AES_DisableIT ( hal_aes_handle_t * haes , uint32_t interrupt )

Disable the AES interrupt.

Parameters :

• haes – Specifies the AES handle

• interrupt – AES Interrupt This parameter can be a combination of the following values:

  • HAL_AES_IT_RDWRERR Error interrupt (used for RDERR and WRERR)

  • HAL_AES_IT_CC Computation Complete interrupt

  • HAL_AES_IT_KERR Key error interrupt

  • HAL_AES_IT_RNGERR RNG error interrupt

AES Processing Key functions

STM32C5A3xx

group AES_Exported_Functions_Group7

This subsection provides a set of functions allowing AES key processing:

• HAL_AES_WrapKey():Allowing to wrap an SAES application key

• HAL_AES_UnwrapKey():Allowing to unwrap the wrapped key to be used by SAES peripheral to encrypt/decrypt messages

• HAL_AES_EncryptSharedKey():Allowing to encrypt an SAES application key in share mode

• HAL_AES_DecryptSharedKey():Allowing to decrypt the SAES encrypted key to be shared with AES peripheral

Functions

hal_status_t HAL_AES_WrapKey ( hal_aes_handle_t * haes , const uint32_t * p_key_in , hal_aes_key_size_t key_size , uint32_t * p_key_output , uint32_t timeout_ms )

Encrypt an application key with SAES HW keys(wrapper key). This API is only available with SAES instance.

Note

This API aims to build a secure application context following this sequence:

• Call HAL_AES_WrapKey() API which encrypts the application key and write it into the output key buffer

• Delete the original key at the application level

• When need to use the original application key to encrypt/decrypt messages, call the HAL_AES_UnwrapKey() API which unwraps the encrypted key using the same wrapper key and load the unexposed result into registers

Warning

The key size must be the same one as the wrapper key which is provided as a parameter of the HAL_AES_SetHWKey() API

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_key_in – Pointer to uint32_t input key provided by the user to be encrypted with a HW key

• key_size – AES key size with a hal_aes_key_size_t type

• p_key_output – Pointer to uint32_t output key provided by the user to be filled with the encrypted application key

• timeout_ms – Specify Timeout value in milliseconds

Return values :

• HAL_INVALID_PARAM – Invalid param return when:

  • The handle instance is not the SAES one

  • The provided application input key pointer is null

  • The provided application output key pointer is null

• HAL_BUSY – Another AES process is ongoing

• HAL_ERROR – Error return when the selected wrapper key is invalid

• HAL_TIMEOUT – AES key wrapping exceeds user timeout

• HAL_OK – AES key wrapping is successfully accomplished

hal_status_t HAL_AES_UnwrapKey ( hal_aes_handle_t * haes , const uint32_t * p_key_in , hal_aes_key_size_t key_size , uint32_t timeout_ms )

Decrypt an application key with the same SAES HW key(wrapper key) used by the HAL_AES_WrapKey() API. This API is only available with SAES instance,.

Note

This API aims to build a secure application context following this sequence:

• Call HAL_AES_WrapKey() API which encrypts the application key and write it into the output key buffer

• Delete the original key at the application level

• When need to use the original application key to encrypt/decrypt messages, call the HAL_AES_UnwrapKey() API which unwraps the encrypted key using the same wrapper key and load the unexposed result into registers

Warning

The key size must be the same one as the wrapper key which is provided as a parameter of the HAL_AES_SetHWKey() API

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_key_in – Pointer to uint32_t key already encrypted with HAL_AES_WrapKey() API

• key_size – AES key size with a hal_aes_key_size_t type

• timeout_ms – Specify Timeout value in milliseconds

Return values :

• HAL_INVALID_PARAM – Invalid param return when:

  • The handle instance is not the SAES one

  • The provided application input key pointer is null

• HAL_BUSY – Another AES process is ongoing

• HAL_ERROR – Error return when the selected wrapper key is invalid or when the key derivation exceeds the dedicated timeout

• HAL_TIMEOUT – AES key unwrapping exceeds user timeout

• HAL_OK – AES key unwrapping is successfully accomplished

hal_status_t HAL_AES_EncryptSharedKey ( hal_aes_handle_t * haes , const uint32_t * p_key_in , hal_aes_key_size_t key_size , uint32_t * p_key_output , uint32_t target_id , uint32_t timeout_ms )

Encrypt an application key to be shared with AES peripheral, using SAES HW key. This API is only available with SAES instance.

Note

This API aims to build a secure application context following this sequence:

• Call HAL_AES_EncryptSharedKey() API to encrypt the application key and write it into the output key buffer

• Delete the original key at the application level

• When need to share the original application key with the specified AES target, call the HAL_AES_DecryptSharedKey() API which decrypts the encrypted key using the same SAES HW keys (wrapper key) and automatically transfers the unreadable result to the target via secure HW buses. This target must be configured with the HAL_AES_SetSharedKey() API, then the target keys registers are loaded automatically with the transferred key.

Warning

The key size must be the same one as the wrapper key which is provided as a parameter of the HAL_AES_SetHWKey() API

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_key_in – Pointer to uint32_t input key provided by the user to be encrypted

• key_size – AES key size with a hal_aes_key_size_t type

• p_key_output – Pointer to uint32_t output key provided by the user to be filled with the encrypted application key

• target_id – Specify which AES target can receive the SAES shared key 00: AES peripheral

• timeout_ms – Specify Timeout value in milliseconds

Return values :

• HAL_INVALID_PARAM – Invalid param return when:

  • The handle instance is not the SAES one

  • The provided application input key pointer is null

  • The provided application output key pointer is null

• HAL_BUSY – Another AES process is ongoing

• HAL_ERROR – Error return when the selected wrapper key is invalid

• HAL_TIMEOUT – AES key wrapping exceeds user timeout

• HAL_OK – AES key wrapping is successfully accomplished

hal_status_t HAL_AES_DecryptSharedKey ( hal_aes_handle_t * haes , const uint32_t * p_key_in , hal_aes_key_size_t key_size , uint32_t target_id , uint32_t timeout_ms )

Decrypt an application key to be shared with AES peripheral with the same SAES HW key (wrapper key) used by the HAL_AES_EncryptSharedKey() API. This API is only available with SAES instance.

Note

This API aims to build a secure application context following this sequence:

• Call HAL_AES_EncryptSharedKey() API to encrypt the application key and write it into the output key buffer

• Delete the original key at the application level

• When need to share the original application key with the specified AES target, call the HAL_AES_DecryptSharedKey() API which decrypts the encrypted key using the same SAES HW keys (wrapper key) and automatically transfers the unreadable result to the target via secure HW buses. This target must be configured with the HAL_AES_SetSharedKey() API, then the target keys registers are loaded automatically with the transferred key.

Warning

The key size must be the same one as the wrapper key which is provided as a parameter of the HAL_AES_SetHWKey() API

Parameters :

• haes – Pointer to a hal_aes_handle_t structure

• p_key_in – Pointer to uint32_t input key provided by the user to be encrypted parameters of the application key and the selected wrapper key (The key to be used to encrypt the key application)

• key_size – AES key size with a hal_aes_key_size_t type

• target_id – Specify which target can read the SAES key registers after a decryption 00: AES peripheral

• timeout_ms – Specify Timeout value in milliseconds

Return values :

• HAL_INVALID_PARAM – Invalid param return when:

  • The handle instance is not the SAES one

  • The provided application input key pointer is null

• HAL_BUSY – Another AES process is ongoing

• HAL_ERROR – Error return when the selected wrapper key is invalid or when the key derivation exceeds the dedicated timeout

• HAL_TIMEOUT – AES key unwrapping exceeds user timeout

• HAL_OK – AES key unwrapping is successfully accomplished